<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Attributed Variable Handlers
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot099.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot093.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot101.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc224">16.7</A>&nbsp;&nbsp;Attributed Variable Handlers</H2><UL>
<LI><A HREF="umsroot100.html#toc126">Printing Attributed Variables</A>
</UL>

<A NAME="metahandlers"></A>
An attributed variable is a variable with some additional information
which is ignored by ordinary <I>object level</I> system predicates.
<I>Meta level</I> operations on attributed variables are handled by
extensions which know
the contents of their attributes and can specify the outcome
of each operation.
This mechanism is implemented using <I>attributed variable handlers</I>,
<A NAME="@default907"></A>
which are user-defined predicates invoked
whenever an attributed variable occurs in one of the predefined
operations.
The handlers are specified in the attribute declaration
<B>meta_attribute(Name, HandlerList)</B>, the second argument
is a list of handlers in the form
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
[unify:UnifyHandler, test_unify:TUHandler, ...]
</PRE></BLOCKQUOTE>
Handlers for operations which are not specified or those that are
<A HREF="../bips/kernel/control/true-0.html"><B>true/0</B></A><A NAME="@default908"></A> are ignored and never invoked.
If <B>Name</B> is an existing extension, the specified handlers
replace the current ones.<BR>
<BR>
Whenever one of the specified operations detects an attributed variable,
it will invoke all handlers that were declared for it
and each of them receives either the whole attributed variable
or its particular attribute as argument.
The system does not check if the attribute that corresponds
to a given handler is instantiated or not; this means
that the handler must check itself if the attributed variable
contains any attribute information or not.
For instance, if an attributed variable <I>X{a:_, b:_, c:f(a)}</I>
is unified with the attributed variable <I>Y{a:_, b:_, c:f(b)}</I>,
the handlers for the attributes <I>a</I> and <I>b</I> should
treat this as binding of two plain variables
because their attributes were not involved.
Only the handler for <I>c</I> has any work to do here.
The library <B>suspend.pl</B> can be used as a template
<A NAME="@default909"></A>
for writing attributed variable handlers.<BR>
<BR>
The following operations invoke attributed variable handlers:
<UL CLASS="itemize"><LI CLASS="li-itemize">
<B>unify</B>: the usual unification.
<A NAME="@default910"></A>
The handler procedure is
<BLOCKQUOTE CLASS="quote">
unify_handler(+Term, ?Attribute [,SuspAttr])
</BLOCKQUOTE>
The first argument is the term that was unified with the attributed variable,
it is either a nonvariable or an attributed variable.
The second argument is directly the contents of the attribute slot
corresponding to the extension, i.e. it is not the whole attributed variable.
When this handler is invoked, the attributed variable is already bound
to <I>Term</I>.
The optional third argument is the suspend-attribute of the former
variable; it may be needed to wake the variable's 'constrained' suspension
list.<BR>
<BR>
If an attributed variable is unified with a standard variable, the variable is bound
to the attributed variable and no handlers are invoked.
If an attributed variable is unified with another attributed variable or a non-variable,
the attributed variable is bound (like a standard variable) to the other term
<B>and</B> all handlers for the <B>unify</B> operation are invoked. 
Note that several attributed variable bindings can occur e.g. during a head unification
and also during a single unification of compound terms.
The handlers are only invoked at certain trigger points (usually before the
next predicate call).<BR>
<BR>
<LI CLASS="li-itemize"><B>test_unify</B>: the unification which is not supposed
<A NAME="@default911"></A>
to trigger constraints propagation, it is used e.g.
in the <A HREF="../bips/kernel/termcomp/not_unify-2.html"><B>not_unify/2</B></A><A NAME="@default912"></A>
predicate.
The handler procedure is
<BLOCKQUOTE CLASS="quote">
test_unify_handler(+Term, ?Attribute)
</BLOCKQUOTE>
where the arguments are the same as for the unify handler.
During the execution of the handler the attributed variable is bound
to <I>Term</I>, however when all local handlers succeed,
all bindings are undone.<BR>
<BR>
<LI CLASS="li-itemize"><B>compare_instances</B>: computation of instance, subsumption
<A NAME="@default913"></A>
and variance relationship, as performed by the built-ins
<A HREF="../bips/kernel/termcomp/instance-2.html"><B>instance/2</B></A><A NAME="@default914"></A> and
<A HREF="../bips/kernel/termcomp/variant-2.html"><B>variant/2</B></A><A NAME="@default915"></A>.
The handler procedure is
<BLOCKQUOTE CLASS="quote">
instance_handler(-Res, ?TermL, ?TermR)
</BLOCKQUOTE>
and its arguments are similar to the ones of the
<A HREF="../bips/kernel/termcomp/compare_instances-3.html"><B>compare_instances/3</B></A><A NAME="@default916"></A>
predicate.
The handler is invoked with one or both of <I>TermL</I> and <I>TermR</I> being
attributed variables. The task of the handler is to compare the two terms
and instantiate <B>Res</B> to either = (if the terms are variants) or &lt;
(if <I>TermL</I> is a proper instance of <I>TermR</I>). If the terms are
incomparable, the handler should fail. If <I>TermR</I> is proper instance
of <I>TermL</I>, the handler should either return &gt; or fail.
All bindings made in the handler will be undone after processing
the local handlers.<BR>
<BR>
<LI CLASS="li-itemize"><B>copy_term</B>: the handler is invoked when terms are copied by the
<A NAME="@default917"></A>
<A HREF="../bips/kernel/termmanip/copy_term-2.html"><B>copy_term/2</B></A><A NAME="@default918"></A> or
<A HREF="../bips/kernel/termmanip/copy_term_vars-3.html"><B>copy_term_vars/3</B></A><A NAME="@default919"></A> built-ins.
The handler procedure is
<BLOCKQUOTE CLASS="quote">
copy_handler(?AttrVar, ?Copy)
</BLOCKQUOTE>
<I>AttrVar</I> is the attributed variable encountered in the
copied term, <I>Copy</I> is its corresponding variable in the copy.
All extension handlers receive the same arguments.
This means that if the attributed variable should be copied as
an attributed variable, the handler must check if <I>Copy</I> is still
a free variable or if it was already bound to an attributed variable by a previous handler.<BR>
<BR>
<LI CLASS="li-itemize"><B>suspensions</B>: this handler is invoked by the
<A NAME="@default920"></A>
<A HREF="../bips/kernel/suspensions/suspensions-2.html"><B>suspensions/2</B></A><A NAME="@default921"></A> predicate
to collect all the suspension lists inside the attribute.
The handler call pattern is
<BLOCKQUOTE CLASS="quote">
suspensions_handler(?AttrVar, -ListOfSuspLists, -Tail)
</BLOCKQUOTE>
<I>AttrVar</I> is an attributed variable. The handler should bind
<I>ListOfSuspLists</I> to a list containing all the attribute's
suspension lists and ending with <I>Tail</I>.<BR>
<BR>
<LI CLASS="li-itemize"><B>delayed_goals_number</B>: handler is invoked by the
<A NAME="@default922"></A>
<A HREF="../bips/kernel/suspensions/delayed_goals_number-2.html"><B>delayed_goals_number/2</B></A><A NAME="@default923"></A>
predicate.
The handler call pattern is
<BLOCKQUOTE CLASS="quote">
delayed_goals_number_handler(?AttrVar, -Number)
</BLOCKQUOTE>
<I>AttrVar</I> is the attributed variable encountered in the
term, <I>Number</I> is the number of delayed
goals occurring in this attribute.
Its main purpose is for the first-fail selection predicates,
i.e. it should return the number of constraints imposed on
the variable.<BR>
<BR>
<LI CLASS="li-itemize"><B>get_bounds</B>:
<A NAME="@default924"></A>
 This handler is used by the predicate
 <A HREF="../bips/kernel/termmanip/get_var_bounds-3.html"><B>get_var_bounds/3</B></A><A NAME="@default925"></A>
 to retrieve information about the lower and upper bound of a numeric
 variable. 
 The handler should therefore only be defined if the attribute contains
 that kind of information. The handler call pattern is
 <BLOCKQUOTE CLASS="quote">
 get_bounds_handler(?AttrVar, -Lwb, -Upb)
 </BLOCKQUOTE>
 The handler is only invoked if the variable has the corresponding
 (non-empty) attribute.
 The handler should bind <I>Lwb</I> and <I>Upb</I> to numbers
 (any numeric type) reflecting the attribute's information about lower
 and upper bound of the variable, respectively.
 If different attributes return different bounds information,
 <A HREF="../bips/kernel/termmanip/get_var_bounds-3.html"><B>get_var_bounds/3</B></A><A NAME="@default926"></A>
 will return the intersection of these bounds. This can be empty (Lwb &gt; Upb).<BR>
<BR>
<LI CLASS="li-itemize"><B>set_bounds</B>:
<A NAME="@default927"></A>
 This handler is used by the predicate
 <A HREF="../bips/kernel/termmanip/set_var_bounds-3.html"><B>set_var_bounds/3</B></A><A NAME="@default928"></A>
 to distribute information about the lower and upper bound of a numeric
 variable to all its existing attributes. 
 The handler should therefore only be defined if the attribute can
 incorporate this kind of information. The handler call pattern is
 <BLOCKQUOTE CLASS="quote">
 set_bounds_handler(?AttrVar, +Lwb, +Upb)
 </BLOCKQUOTE>
 The handler is only invoked if the variable has the corresponding
 (non-empty) attribute.
 <I>Lwb</I> and <I>Upb</I> are the numbers that were passed to
 <A HREF="../bips/kernel/termmanip/set_var_bounds-3.html"><B>set_var_bounds/3</B></A><A NAME="@default929"></A>, and the handler is expected to update its
 own bounds representation accordingly.<BR>
<BR>
<LI CLASS="li-itemize"><B>print</B>: attribute printing in
<A NAME="@default930"></A>
<A HREF="../bips/kernel/ioterm/write-1.html"><B>write/1,2</B></A><A NAME="@default931"></A>,
<A HREF="../bips/kernel/ioterm/writeln-1.html"><B>writeln/1,2</B></A><A NAME="@default932"></A>,
<A HREF="../bips/kernel/ioterm/printf-2.html"><B>printf/2,3</B></A><A NAME="@default933"></A>
when the <B>m</B> option is specified.
The handler procedure is
<BLOCKQUOTE CLASS="quote">
print_handler(?AttrVar, -Attribute)
</BLOCKQUOTE>
<I>AttrVar</I> is the attributed variable being printed, <I>Attribute</I>
is the term which will be printed as a value for this attribute,
prefixed by the attribute name.
If no handler is specified for an attribute, or the print handler fails, 
the attribute will not be printed.</UL>
The following handlers are still supported for compatibility,
but their use is not recommened:
<UL CLASS="itemize"><LI CLASS="li-itemize">
<B>pre_unify</B>: this is another handler which can be invoked on
<A NAME="@default934"></A>
normal unification, but it is called <I>before</I> the unification
itself occurs.
The handler procedure is
<BLOCKQUOTE CLASS="quote">
pre_unify_handler(?AttrVar, +Term)
</BLOCKQUOTE>
The first argument is the attributed variable to be unfied,
the second argument is the term it is going to be unified with.
This handler is provided only for compatibility with SICStus Prolog
and its use is not recommended, because it is less efficient
than the <B>unify</B> handler and because its semantics is somewhat
unclear, there may be cases where changes inside this handler
may have unexpected effects.<BR>
<BR>
<LI CLASS="li-itemize"><B>delayed_goals</B>: this handler is superseded by the
<A NAME="@default935"></A>
suspensions-handler, which should be preferred. If there is no suspensions-
handler, this handler is invoked by the obsolete
<A HREF="../bips/kernel/suspensions/delayed_goals-2.html"><B>delayed_goals/2</B></A><A NAME="@default936"></A> predicate.
The handler procedure is
<BLOCKQUOTE CLASS="quote">
delayed_goals_handler(?AttrVar, ?GoalList, -GoalCont)
</BLOCKQUOTE>
<I>AttrVar</I> is the attributed variable encountered in the
term, <I>GoalList</I> is an open-ended list of all delayed
goals in this attribute and <I>GoalCont</I> is the
tail of this list.</UL>
<A NAME="toc126"></A>
<H3 CLASS="subsection"><A NAME="htoc225">16.7.1</A>&nbsp;&nbsp;Printing Attributed Variables</H3>
<A NAME="@default937"></A>
<A NAME="@default938"></A>
The different output predicates treat attributed variables differently.
The <A HREF="../bips/kernel/ioterm/write-1.html"><B>write/1</B></A><A NAME="@default939"></A> predicate prints
the attributes using the print-handlers,
while <A HREF="../bips/kernel/ioterm/writeq-1.html"><B>writeq/1</B></A><A NAME="@default940"></A> prints the whole attribute, so that the attributed variable
can be read back.
The <A HREF="../bips/kernel/ioterm/printf-2.html"><B>printf/2</B></A><A NAME="@default941"></A> predicate has two options to be combined with
the <B>w</B> format: <B>M</B> forces the whole attributed variable to be printed
together with all its attributes in the standard format, so that
it can be read back in.
With the <B>m</B> option the attributed variable is printed using the handlers
defined for the <B>print</B> operation.
If there is only one handled attribute, the attributed variable is printed as
<BLOCKQUOTE CLASS="quote">
X{Attr}
</BLOCKQUOTE>
where <I>Attr</I> is the value obtained from the handler.
If there are several handled attributes, all attributes are qualified
like in
<BLOCKQUOTE CLASS="quote">
X{a:A, b:B, c:C}.
</BLOCKQUOTE>
An attributed variable <TT>X{m:a}</TT> with <B>print</B> handler <B>=/2</B>
can thus be printed in different ways, e.g.:
<SUP><A NAME="text25" HREF="umsroot093.html#note25">1</A></SUP>
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
printf("%w", [X{m:a}])   or write(X{m:a}):    X   
printf("%vMw", [X{m:a}]) or writeq(X{m:a}):   _g246{suspend : _g242, m : a}
printf("%mw", [X{m:a}]):                      X{a}
printf("%Mw", [X{m:a}]):                      X{suspend : _g251, m : a}
printf("%Vmw", [X{m:a}]):                     X_g252{a}
</PRE></BLOCKQUOTE>

<A NAME="@default942"></A>
Write macros for attributed variables are not allowed because one extension alone
should not decide whether the other attributes will be printed or not.<BR>
<BR>
<HR>
<A HREF="umsroot099.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot093.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot101.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
